<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.6.0">
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>TCP-Relay</title>
<meta name="GENERATOR" content="Modular DocBook HTML Stylesheet Version 1.79">
</head>
<body class="article" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="ARTICLE">
<div class="TITLEPAGE">
<h1 class="title"><a name="AEN2" id="AEN2">TCP-Relay</a></h1>
<h3 class="author"><a name="AEN4" id="AEN4">Marc Huber</a></h3>
<span class="releaseinfo">$Id: c7794025437463f7df2ee9bde97656535d6c6243 $<br></span>
<hr></div>
<div class="TOC">
<dl>
<dt><b>Table of Contents</b></dt>
<dt>1. <a class="lk" href="#AEN9">Introduction</a></dt>
<dd>
<dl>
<dt>1.1. <a class="lk" href="#AEN13">Download</a></dt>
</dl>
</dd>
<dt>2. <a class="lk" href="#AEN18">Operation</a></dt>
<dd>
<dl>
<dt>2.1. <a class="lk" href="#AEN32">Command line syntax</a></dt>
<dt>2.2. <a class="lk" href="#AEN53">Signals</a></dt>
<dt>2.3. <a class="lk" href="#AEN66">Event mechanism selection</a></dt>
<dt>2.4. <a class="lk" href="#AEN92">Configuration Syntax</a></dt>
<dd>
<dl>
<dt>2.4.1. <a class="lk" href="#AEN188">Railroad Diagram</a></dt>
</dl>
</dd>
<dt>2.5. <a class="lk" href="#AEN198">Sample configuration</a></dt>
</dl>
</dd>
<dt>3. <a class="lk" href="#AEN202">Bugs</a></dt>
<dt>4. <a class="lk" href="#AEN208">Copyrights and Acknowledgements</a></dt>
</dl>
</div>
<div class="section">
<h2 class="section"><a name="AEN9" id="AEN9">1. Introduction</a></h2>
<p><span class="bold"><b class="emphasis">tcprelay</b></span> is a TCP connection forwarder with load balancing capabilities. If compiled with TLS support, it may be used as SSL encryption wrapper.</p>
<div class="section">
<hr>
<h3 class="section"><a name="AEN13" id="AEN13">1.1. Download</a></h3>
<p>You can download the source code from the GitHub repository at <a class="lk" href="https://github.com/MarcJHuber/event-driven-servers/" target="_top">https://github.com/MarcJHuber/event-driven-servers/</a>. On-line documentation is available via <a class="lk" href="https://projects.pro-bono-publico.de/event-driven-servers/doc/" target="_top">https://projects.pro-bono-publico.de/event-driven-servers/doc/</a>, too.</p>
</div>
</div>
<div class="section">
<hr>
<h2 class="section"><a name="AEN18" id="AEN18">2. Operation</a></h2>
<p>This section gives a brief and basic overview on how to run <span class="bold"><b class="emphasis">tcprelay</b></span>.</p>
<p>In earlier versions, <span class="bold"><b class="emphasis">tcprelay</b></span> wasn't a standalone program but had to be invoked by <span class="bold"><b class="emphasis">spawnd</b></span>. This has changed, as <span class="bold"><b class="emphasis">spawnd</b></span> is now part of the <span class="bold"><b class="emphasis">tcprelay</b></span> binary. However, using a dedicated <span class="bold"><b class="emphasis">spawnd</b></span> process is still possible and, more importantly, the <span class="bold"><b class="emphasis">spawnd</b></span> configuration options and documentation remain valid.</p>
<p><span class="bold"><b class="emphasis">tcprelay</b></span> may use auxilliary <span class="bold"><b class="emphasis">MAVIS</b></span> backend modules for authentication and authorization.</p>
<div class="section">
<hr>
<h3 class="section"><a name="AEN32" id="AEN32">2.1. Command line syntax</a></h3>
<p>The only mandatory argument is the path to the configuration file:</p>
<pre class="screen">tcprelay [ <span class="emphasis"><i class="emphasis">-P</i></span> ] [ <span class="emphasis"><i class="emphasis">-d level</i></span> ]  [ <span class="emphasis"><i class="emphasis">-i child_id</i></span> ] <span class="emphasis"><i class="emphasis">configuration-file</i></span> [ <span class="emphasis"><i class="emphasis">id</i></span> ]</pre>
<p>If the program was compiled with CURL support, <span class="emphasis"><i class="emphasis">configuration-file</i></span> may be an URL.</p>
<p>Keep the <tt class="literal">-P</tt> option in mind - it is imperative that the configuration file supplied is syntactically correct, as the daemon won't start if there are any parsing errors at start-up.</p>
<p>The <tt class="literal">-d</tt> switch enables debugging. You most likely don't want to use this. Read the source if you need to.</p>
<p>The <tt class="literal">-i</tt> option is only honoured if the build-in <span class="bold"><b class="emphasis">spawnd</b></span> functionality is used. In that case, it selects the configuration ID for <span class="bold"><b class="emphasis">tcprelay</b></span>, while the optional last argument <span class="emphasis"><i class="emphasis">id</i></span> sets the ID of the <span class="bold"><b class="emphasis">spawnd</b></span> configuration section.</p>
</div>
<div class="section">
<hr>
<h3 class="section"><a name="AEN53" id="AEN53">2.2. Signals</a></h3>
<p>Both the master (that's the process running the <span class="bold"><b class="emphasis">spawnd</b></span> code) and the child processes (running the <span class="bold"><b class="emphasis">tcprelay</b></span> code) intercept the <tt class="literal">SIGHUP</tt> signal:</p>
<ul>
<li>
<p>The master process will restart upon reception of <tt class="literal">SIGHUP</tt>, re-reading the configuration file. The child processes will recognize that the master process is no longer available. It will continue to serve the existing connections and terminate when idle.</p>
</li>
<li>
<p>If <tt class="literal">SIGHUP</tt> is sent to a child process it will stop accepting new connections from its master process. It will continue to serve the existing connections and terminate when idle.</p>
</li>
</ul>
</div>
<div class="section">
<hr>
<h3 class="section"><a name="AEN66" id="AEN66">2.3. Event mechanism selection</a></h3>
<p>Several level-triggered event mechanisms are supported. By default, the one best suited for your operating system will be used. However, you may use the environment variable <tt class="literal">IO_POLL_MECHANISM</tt> to select a specific one.</p>
<p>The following event mechanisms are supported (in order of preference):</p>
<ul>
<li>
<p>port (Sun Solaris 10 and higher only, <tt class="literal">IO_POLL_MECHANISM=32</tt>)</p>
</li>
<li>
<p>kqueue (*BSD and Darwin only, <tt class="literal">IO_POLL_MECHANISM=1</tt>)</p>
</li>
<li>
<p>/dev/poll (Sun Solaris only, <tt class="literal">IO_POLL_MECHANISM=2</tt>)</p>
</li>
<li>
<p>epoll (Linux only, <tt class="literal">IO_POLL_MECHANISM=4</tt>)</p>
</li>
<li>
<p>poll (<tt class="literal">IO_POLL_MECHANISM=8</tt>)</p>
</li>
<li>
<p>select (<tt class="literal">IO_POLL_MECHANISM=16</tt>)</p>
</li>
</ul>
<p>Environment variables can be set in the configuration file at top-level:</p>
<pre class="screen">setenv IO_POLL_MECHANISM = 4</pre></div>
<div class="section">
<hr>
<h3 class="section"><a name="AEN92" id="AEN92">2.4. Configuration Syntax</a></h3>
<p>A single configuration file is sufficient for configuring both <span class="bold"><b class="emphasis">spawnd</b></span> and <span class="bold"><b class="emphasis">tcprelay</b></span>. The basic format for this file is:</p>
<pre class="screen">id = spawnd {
    # spawnd configuration directives
}

id = tcprelay {
    # tcprelay configuration directives
}</pre>
<p>For example, the <tt class="literal">spawnd</tt> section could look similar to:</p>
<pre class="screen">    listen = { port = 80}
    spawn = { exec /usr/local/libexec/tcprelay }</pre>
<p>This tells spawnd to accept connections on the port given, and feed them to a <span class="bold"><b class="emphasis">tcprelay</b></span> process. Please see the <span class="bold"><b class="emphasis">spawnd</b></span> documentation for more configuration details.</p>
<p><span class="bold"><b class="emphasis">tcprelay</b></span> has its own set of configuration directives:</p>
<ul>
<li>
<p><tt class="literal">local address =</tt> <span class="emphasis"><i class="emphasis">addr</i></span></p>
<p>Specifies the local address used for outgoing connections.</p>
</li>
<li>
<p><tt class="literal">rebalance =</tt> <span class="emphasis"><i class="emphasis">n</i></span></p>
<p>Re-balances peers after <span class="emphasis"><i class="emphasis">n</i></span> requests. May be used to reactivate dead peers. Use with care. Default: unset.</p>
</li>
<li>
<p><tt class="literal">remote = {</tt> ... <tt class="literal">}</tt></p>
<p>The <tt class="literal">remote</tt> sections tell <span class="bold"><b class="emphasis">tcprelay</b></span> where to relay connections to. Valid configuration directives inside the curly brackets are:</p>
<ul>
<li>
<p><tt class="literal">address =</tt> <span class="emphasis"><i class="emphasis">IPAddress</i></span></p>
</li>
<li>
<p><tt class="literal">port =</tt> <span class="emphasis"><i class="emphasis">TCPPort</i></span></p>
</li>
<li>
<p><tt class="literal">protocol =</tt> ( <tt class="literal">TCP</tt> | <tt class="literal">SCTP</tt>)</p>
</li>
<li>
<p><tt class="literal">weight =</tt> <span class="emphasis"><i class="emphasis">Weight</i></span></p>
</li>
</ul>
<p>Both the <tt class="literal">address</tt> and <tt class="literal">port</tt> directives are mandatory. The load balancing factor <span class="emphasis"><i class="emphasis">weight</i></span> is optional and defaults to 1. Its value should somehow correspond to the load a destination can handle.</p>
</li>
<li>
<p><tt class="literal">retire =</tt> <span class="emphasis"><i class="emphasis">count</i></span></p>
<p>If set, the daemon will terminate after processing <span class="emphasis"><i class="emphasis">count</i></span> sessions, what may be useful to remedy the effects of memory leaks. By default, this is not set.</p>
</li>
<li>
<p><tt class="literal">syslog</tt> ( ( <tt class="literal">ident =</tt> Ident) | ( <tt class="literal">severity =</tt> Level ) | ( <tt class="literal">facility =</tt> Facility))</p>
<p>Selects syslog <span class="emphasis"><i class="emphasis">ident</i></span>, <span class="emphasis"><i class="emphasis">severity</i></span> and <span class="emphasis"><i class="emphasis">facility</i></span>. Defaults to:</p>
<pre class="screen">syslog ident = <span class="emphasis"><i class="emphasis">program-name</i></span>
syslog facility = UUCP
syslog severity = INFO</pre></li>
<li>
<p><tt class="literal">idle timeout =</tt><span class="emphasis"><i class="emphasis">Seconds</i></span></p>
<p>Set session timeout (default: <tt class="literal">0</tt>).</p>
</li>
<li>
<p><tt class="literal">tls cert-file =</tt> <span class="emphasis"><i class="emphasis">CertFile</i></span></p>
<p><tt class="literal">tls key-file =</tt> <span class="emphasis"><i class="emphasis">KeyFile</i></span></p>
<p><tt class="literal">tls passphrase =</tt> <span class="emphasis"><i class="emphasis">PassPhrase</i></span></p>
<p>If compiled with TLS/SSL, <span class="emphasis"><i class="emphasis">PassPhrase</i></span>, <span class="emphasis"><i class="emphasis">CertFile</i></span> and <span class="emphasis"><i class="emphasis">KeyFile</i></span> may be specified using this option.</p>
<p><span class="emphasis"><i class="emphasis">KeyFile</i></span> may be omitted, it defaults to <span class="emphasis"><i class="emphasis">CertFile</i></span>.</p>
</li>
</ul>
<div class="section">
<hr>
<h4 class="section"><a name="AEN188" id="AEN188">2.4.1. Railroad Diagram</a></h4>
<div class="mediaobject">
<p><img alt="" src="railroad/tcprelay/Config.svg"></p>
<div class="caption">
<p>Railroad diagram: TcprelayConfig</p>
</div>
</div>
</div>
</div>
<div class="section">
<hr>
<h3 class="section"><a name="AEN198" id="AEN198">2.5. Sample configuration</a></h3>
<pre class="screen">#!/usr/local/sbin/spawnd
id = spawnd {
    listen = { port = 2222 }
    listen = { address = ::0 port = 2222 }
    listen = { ::0 port = 2224 }
    listen = { port = 2225 tls = yes }
    spawn {
        users max = 4000
        users min = 10
        servers min = 1
        servers max = 20
    }
}

id = tcprelay {
        remote = { address = 169.254.1.2 port = 22 }
        ssl cert = /some/where/sample.pem
        ssl passphrase =  12345
}</pre></div>
</div>
<div class="section">
<hr>
<h2 class="section"><a name="AEN202" id="AEN202">3. Bugs</a></h2>
<ul>
<li>
<p>TLS re-negotiation is currently untested and may or may not work.</p>
</li>
</ul>
</div>
<div class="section">
<hr>
<h2 class="section"><a name="AEN208" id="AEN208">4. Copyrights and Acknowledgements</a></h2>
<p>Please see the source for copyright and licensing information of individual files.</p>
<ul>
<li>
<p><span class="bold"><b class="emphasis">The following applies if the software was compiled with TLS support:</b></span></p>
<p>This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (<a class="lk" href="http://www.openssl.org/" target="_top">http://www.openssl.org/</a>).</p>
<p>This product includes cryptographic software written by Eric Young (<code class="email">&lt;<a class="lk" href='mailto:eay@cryptsoft.com"'>eay@cryptsoft.com"</a>&gt;</code>).</p>
</li>
<li>
<p><span class="bold"><b class="emphasis">Portions of the parsing code are taken from Cisco's tac_plus developers kit which is distributed under the following license:</b></span></p>
<p>Copyright (c) 1995-1998 by Cisco systems, Inc.</p>
<p>Permission to use, copy, modify, and distribute this software for any purpose and without fee is hereby granted, provided that this copyright and permission notice appear on all copies of the software and supporting documentation, the name of Cisco Systems, Inc. not be used in advertising or publicity pertaining to distribution of the program without specific prior permission, and notice be given in supporting documentation that modification, copying and distribution is by permission of Cisco Systems, Inc.</p>
<p>Cisco Systems, Inc. makes no representations about the suitability of this software for any purpose. THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.</p>
</li>
<li>
<p><span class="bold"><b class="emphasis">The code written by Marc Huber is distributed under the following license:</b></span></p>
<p>Copyright (C) 1999-2022 Marc Huber (<code class="email">&lt;<a class="lk" href="mailto:Marc.Huber@web.de">Marc.Huber@web.de</a>&gt;</code>). All rights reserved.</p>
<p>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:</p>
<ol type="1">
<li>
<p>Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.</p>
</li>
<li>
<p>Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.</p>
</li>
<li>
<p>The end-user documentation included with the redistribution, if any, must include the following acknowledgment:</p>
<a name="AEN238" id="AEN238"></a>
<blockquote class="BLOCKQUOTE">
<p>This product includes software developed by Marc Huber (<code class="email">&lt;<a class="lk" href="mailto:Marc.Huber@web.de">Marc.Huber@web.de</a>&gt;</code>).</p>
</blockquote>
<p>Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.</p>
</li>
</ol>
<p>THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ITS AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</p>
</li>
</ul>
</div>
</div>
</body>
</html>
